[Server] Oauth2 based on middleware by sveneld · Pull Request #221 · modelcontextprotocol/php-sdk

sveneld · 2026-01-12T11:43:41Z

Motivation and Context

Implementation of OAuth based on middlewares from #218

How Has This Been Tested?

Breaking Changes

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

…into middleware

chr-hertel · 2026-01-18T21:24:31Z

Thanks @sveneld - it will take some time for me to give some proper feedback here, just to let you know - needs quite some focus & attention - still really appreciated!

chr-hertel

Hi again @sveneld! This is great already - went to a first round of very detailed review directly. Thanks again for working on this! 🙏

Didn't manage to go through all, but dropping the first round of comments.

chr-hertel · 2026-01-26T20:20:12Z

examples/server/oauth-keycloak/README.md

+
+5. **Use with MCP Inspector:**
+
+The MCP Inspector doesn't support OAuth out of the box, but you can test using curl or build a custom client.


This was a bit unexpected to me since I saw this in inspector:

chr-hertel · 2026-01-26T20:21:05Z

examples/server/oauth-keycloak/README.md

Works right away 💪 👍

chr-hertel · 2026-01-26T20:23:08Z

examples/server/oauth-keycloak/server.php

+// Configuration from environment
+// External URL is what clients use and what appears in tokens
+$keycloakExternalUrl = getenv('KEYCLOAK_EXTERNAL_URL') ?: 'http://localhost:8180';
+// Internal URL is how this server reaches Keycloak (Docker network)
+$keycloakInternalUrl = getenv('KEYCLOAK_INTERNAL_URL') ?: 'http://keycloak:8080';
+$keycloakRealm = getenv('KEYCLOAK_REALM') ?: 'mcp';
+$mcpAudience = getenv('MCP_AUDIENCE') ?: 'mcp-server';
+
+// Issuer is what appears in the token (external URL)
+$issuer = rtrim($keycloakExternalUrl, '/').'/realms/'.$keycloakRealm;
+// JWKS URI uses internal URL to reach Keycloak within Docker network
+$jwksUri = rtrim($keycloakInternalUrl, '/').'/realms/'.$keycloakRealm.'/protocol/openid-connect/certs';


I think it's fair to hard-code the values here instead of using getenv

chr-hertel · 2026-01-26T20:24:42Z

examples/server/oauth-keycloak/server.php

+// Create logger
+$logger = new class extends AbstractLogger {
+    public function log($level, \Stringable|string $message, array $context = []): void
+    {
+        $logMessage = sprintf("[%s] %s\n", strtoupper($level), $message);
+        error_log($logMessage);
+    }
+};


can we use the logger() provided by the examples/bootstrap.php file? would be more consistent with other examples or is there a particular reason not to?

chr-hertel · 2026-01-26T20:26:02Z

examples/server/oauth-keycloak/server.php

+$server = Server::builder()
+    ->setServerInfo('OAuth Keycloak Example', '1.0.0')
+    ->setLogger($logger)
+    ->setSession(new FileSessionStore('/tmp/mcp-sessions'))


to be more consistent with other examples:

Suggested change

->setSession(new FileSessionStore('/tmp/mcp-sessions'))

->setSession(new FileSessionStore(__DIR__.'/sessions'))

chr-hertel · 2026-01-26T20:51:22Z

src/Server/Transport/Middleware/JwtTokenValidator.php

+        $response = $this->httpClient->sendRequest($request);
+
+        if ($response->getStatusCode() >= 400) {
+            throw new \RuntimeException(sprintf(


please use package specific exceptions: Mcp\Exception\RuntimeException

below as well, please

chr-hertel · 2026-01-26T20:52:16Z

src/Server/Transport/Middleware/JwtTokenValidator.php

+
+        $response = $this->httpClient->sendRequest($request);
+
+        if ($response->getStatusCode() >= 400) {


i wonder if this would be:

Suggested change

if ($response->getStatusCode() >= 400) {

if (200 !== $response->getStatusCode()) {

our expectations here are quite clear, right?

chr-hertel · 2026-01-26T20:53:07Z

src/Server/Transport/Middleware/JwtTokenValidator.php

+        $tokenIssuer = $claims['iss'];
+        $expectedIssuers = \is_array($this->issuer) ? $this->issuer : [$this->issuer];
+
+        return \in_array($tokenIssuer, $expectedIssuers, true);


$tokenIssuer can be inlined:

Suggested change

return \in_array($tokenIssuer, $expectedIssuers, true);

return \in_array($claims['iss'], $expectedIssuers, true);

chr-hertel · 2026-01-26T20:54:24Z

src/Server/Transport/Middleware/JwtTokenValidator.php

would be great to have tests for this class

chr-hertel · 2026-01-26T20:55:08Z

src/Server/Transport/Middleware/AuthorizationResult.php

+ *
+ * @author Volodymyr Panivko <sveneld300@gmail.com>
+ */
+class AuthorizationResult


Suggested change

class AuthorizationResult

final class AuthorizationResult

sveneld · 2026-01-28T15:33:08Z

@chr-hertel I updated pull request

Volodymyr Panivko and others added 3 commits December 29, 2025 16:04

Add Middleware handlers to StreamableHttpTransport

6988e5b

Merge branch 'main' of https://github.com/modelcontextprotocol/php-sdk …

af2b28b

…into middleware

OAuth Implementation based on middleware

6ac6671

sveneld requested review from CodeWithKyrian, Nyholm and chr-hertel as code owners January 12, 2026 11:43

sveneld mentioned this pull request Jan 12, 2026

Add Middleware handlers to StreamableHttpTransport #218

Open

9 tasks

chr-hertel changed the title ~~Oauth2 based on middleware~~ [Server] Oauth2 based on middleware Jan 23, 2026

chr-hertel added Server Issues & PRs related to the Server component auth Issues and PRs related to Authentication / OAuth labels Jan 23, 2026

chr-hertel requested changes Jan 26, 2026

View reviewed changes

OAuth Implementation based on middleware

79a9916


		5. Use with MCP Inspector:

		The MCP Inspector doesn't support OAuth out of the box, but you can test using curl or build a custom client.

	->setSession(new FileSessionStore('/tmp/mcp-sessions'))
	->setSession(new FileSessionStore(__DIR__.'/sessions'))


		$response = $this->httpClient->sendRequest($request);

		if ($response->getStatusCode() >= 400) {

	if ($response->getStatusCode() >= 400) {
	if (200 !== $response->getStatusCode()) {

	return \in_array($tokenIssuer, $expectedIssuers, true);
	return \in_array($claims['iss'], $expectedIssuers, true);

Conversation

sveneld commented Jan 12, 2026

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

chr-hertel commented Jan 18, 2026

Uh oh!

chr-hertel left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sveneld commented Jan 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants